home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / BARNET / FREENET / HAWKINS / G0PSCAN- / !g0PScan / 3rdParty / ZapRedraw / Redraw < prev    next >
Text File  |  1998-01-18  |  41KB  |  946 lines

  1. *************************************************************************
  2. * >Redraw - Documentation for the ZapRedraw module v0.22        *
  3. *************************************************************************
  4.  
  5. Summary:
  6. --------
  7.  
  8. The module ZapRedraw provides the "ZapRedraw_" SWI's which are capable of
  9. drawing a rectangle of text characters on screen. It offers the following
  10. features:
  11.  
  12. * Redraw may be by direct screen access (henceforth DSA) where the
  13.   data is poked into the screen memory or by the standard VDU redraw.
  14.   
  15. * Full colour provided (with your own definable palette). Supports up to 32
  16.   bits per pixel in DSA mode and 24 bit colour in VDU mode.
  17.  
  18. * DSA redraw can handle any size of bitmap characters. Special optimised
  19.   code is provided for 8 pixel wide characters in all modes.
  20.   Also 8*8 and 8*16 character sizes are given priority.
  21.   Up to 65536 characters can be defined.
  22.   
  23. * VDU redraw mode can handle any font, at any size and aspect ratio.
  24.  
  25. * Support is provided for cursors.
  26.  
  27. * Many extra SWIs perform all the work of creating cached bitmaps, updating
  28.   them on a mode change etc. SWI's are also provided for creating palettes
  29.   and other functions related to the redraw.
  30.  
  31. * An example program is provided which can be used as a template.
  32.   
  33. Limitations:
  34.  
  35. * All characters are equally spaced. Proportional spacing is not supported.
  36.  
  37. Copyright:
  38. ----------
  39.  
  40. The ZapRedraw module is copyright Dominic Symes 1994-1997. Please contact
  41. him if you wish to use it in a program other than Zap. See the Zap Copyright
  42. file for his address.
  43.  
  44. Definitions required for the SWI's
  45. ==================================
  46.  
  47. ZapRedraw chunk prefix: ZapRedraw
  48. ZapRedraw chunk number: &48480
  49.  
  50. All SWI numbers below are given as offsets from the chunk number.
  51.  
  52. 'DSA' means direct screen access mode (characters poked into the screen).
  53. 'VDU' means VDU mode (operating system called to draw characters).
  54.  
  55. Pixel co-ordinates are used wherever possible to prevent rounding errors when
  56. OS co-ordinates are not pixel aligned (these errors DO mess things up!).
  57. Pixel co-ordinates are from the top left of the screen with the y axis
  58. descending. By a 'pixel' I mean a hardware pixel (this differs from an OS
  59. pixel in double-pixel emulation modes - this only crops up in the RISC OS 2
  60. MODE 2 wimp!).
  61.  
  62. Zap redraw block:
  63. -----------------
  64.  
  65. For several SWI's, R1 points to a redraw block of the type described below.
  66. The SWI documentation will mention which data in the block is actually used
  67. by that SWI (so should be filled in). Each offset in the block is named with
  68. a name beginning 'r_'. The BASIC program E-Library contains a procedure to
  69. set these variables up should you be using the BASIC assembler. The contents
  70. of some offsets depends on which redraw mode is being used (VDU or DSA), this
  71. is indicated by 'VDU:' and 'DSA:'.
  72.  
  73. Offset    Name        Function
  74.  
  75. &00    r_flags        Flags word determining the type of redraw:
  76.             b0 Clear for DSA mode. Set for VDU redraw mode.
  77.             b1 Set for 'double height mode'. Only valid in DSA
  78.                mode. Draws each raster twice so actual character
  79.                height is 2*r_charh and spacing 2*r_linesp.
  80.             b2 Extension routine provided.
  81.                Only valid in DSA mode. See ZapRedraw_RedrawArea.
  82.             b3 Set if using the multiple font protocol.
  83.                See ZapRedraw_RedrawArea.
  84.             b4 Set if it is OK to use the fast rectangle plot in
  85.                VDU redraw mode (i.e. output is not redirected
  86.                to a sprite or a printer.)
  87.             b3-31 Reserved - set to zero.
  88. &04    r_minx        Min x of redraw (pixels from lhs - inclusive)
  89. &08    r_miny        Min y of redraw (pixels from top - inclusive)
  90. &0C    r_maxx        Max x of redraw (pixels from lhs - exclusive)
  91. &10    r_maxy        Max y of redraw (pixels from top - exclusive)
  92. &14    r_screen    DSA: Address of screen to write to or 0 to read the
  93.                  current screen address.
  94.             VDU: ignored
  95. &18    r_bpl        DSA: Bytes per raster line of the screen
  96.             VDU: ignored
  97. &1C    r_bpp        Log base 2 of number of bits per pixel
  98.             (ie 0=2 cols 1=4 cols 2=16 cols 3=256 cols
  99.             4=65536 cols 5=2^32 cols).
  100. &20    r_charw        Width of a character in pixels
  101. &24    r_charh        Height of a character in pixels
  102. &28    r_caddr        DSA: Address of character cache (format below)
  103.             VDU: Pointer to font name or 0 for system font
  104. &2C    r_cbpl        DSA: Number of bytes per cached character line.
  105.             VDU: x os offset of where to print the font char
  106.                  in the character 'box'. (eg 0 for system font)
  107. &30    r_cbpc        DSA: Number of bytes per cached character.
  108.             VDU: y os offset of where to print the font char
  109.                  in the character 'box'. (eg char height-1 for
  110.                  system font as VDU5 plots char downwards).
  111. &34    r_linesp    Line spacing in pixels.
  112. &38    r_data        Address of data (rectangle of characters) to print
  113.             on the screen (format below).
  114. &3C    r_scrollx    Horizontal scroll offset in rectangle of characters
  115.             given in r_data of top left of redraw rectangle.
  116.             This is in pixels from the lhs of the characters.
  117.             Thus it equals n*r_charw+m where n is the number of
  118.             characters in and m is the number of pixels into
  119.             the n'th character.
  120. &40    r_scrolly    Vertical scroll offset in rectangle of characters
  121.             given in r_data of top left of redraw rectangle.
  122.             This is in pixels from the top of the characters.
  123.             Note that in single height mode each line is
  124.             r_charh+r_linesp pixels high and in double height
  125.             mode each line is 2*(r_charh+r_linesp) pixels high.
  126. &44    r_palette    Address of palette to be used for colour translation.
  127.             (see below).
  128. &48    r_for        Foreground colour to use at the start of a line as an
  129.             offset in the palette table.
  130. &4C    r_bac        Background colour to use at the start of a line as
  131.             an offset in the palette table.
  132. &50    r_workarea    Pointer to an area of workspace for the SWI to use.
  133.             The size of this workspace depends on the SWI.
  134.             (It must be word aligned).
  135. &54    r_magx        Log base 2 of number of x os co-ords per pixel.
  136. &58    r_magy      Log base 2 of number of y os co-ords per pixel.
  137. &5C    r_xsize        Width of screen in pixels.
  138. &60    r_ysize        Height of screen in pixels.
  139. &64    r_mode        Current screen mode.
  140.  
  141. Character cache format (r_caddr):
  142. ---------------------------------
  143.  
  144. When using VDU redraw, this should point to the name of the font to use, or
  145. be zero for the system font.
  146.  
  147. When using direct screen access, the module will expect this block to contain
  148. the bitmaps for all the characters it is asked to print. Each character has
  149. size r_cbpc so it will expect to find the bitmap for ASCII character 'n' at
  150. address char_start=(!r_caddr)+n*r_cbpc. The character definition then
  151. consists of r_charh rows of r_cbpl each so r_cbpc=r_charh*r_cbpl. NB r_cbpl
  152. need not be a multiple of 4 so this address need not be word aligned.
  153.  
  154. The format of a row is the same of that for a sprite file except there is
  155. never any lhs wastage. Ie, the first pixel is aligned to the start of the
  156. first word. Each character is r_charw pixels wide and thus requires
  157. N=r_charw<<r_bpp bits of storage. There are special cases when N is small:
  158.  
  159.  If 0<N=<8  then r_cbpl=1 and the top 8-N bits of each byte are wasted.
  160.  If 8<N=<16 then r_cbpl=2 and the top 16-N bits of each byte are wasted.
  161.  If N>16    then r_cbpl is aligned to the next multiple of 4 bytes greater
  162.   or equal to N. (eg 16<N=<32 => r_cbpl=4, 32<N=<64 => r_cbpl=8 etc).
  163.   
  164. The SWI ZapRedraw_CachedCharSize will calculate the values of r_cbpl and
  165. r_cbpc for you from a given size of character.
  166.  
  167. Only TWO colours can be used in the defn of the character. Set all foreground
  168. pixels to 1's and background pixels to 0's. Eg, in a 16 colour mode pixels
  169. will be either 1111 or 0000. Unused bits at the end of the words (or bytes)
  170. are ignored and so can contain rubbish. The real foreground and background
  171. colours are masked in at run time.
  172.  
  173.  Examples:
  174.  
  175.  For 8*8 characters at 1 bit per pixel we have 1 byte per row. Eg "E" may be
  176.  cached as:
  177.                 b0 .. b7
  178.     row0    &7E        01111110
  179.     row1    &06        01100000
  180.     row2    &06        01100000
  181.     row3    &7E        01111110
  182.     row4    &06        01100000
  183.     row5    &06        01100000
  184.     row6    &7E        01111110
  185.     row7    &00        00000000
  186.  
  187.  If it was in a 16 colour mode then there would be one word per row and the
  188.  first rows would be:
  189.                 b0 ......................... b31
  190.     row0    &01111110    00001111111111111111111111110000
  191.     row1    &00000110    00001111111100000000000000000000
  192.     ...
  193.     
  194.  In general you have:
  195.  
  196.     Word 0                    Word (N/4)-1
  197.     b0 .... b31    ...................      b0 ..... b31
  198.     pix0 pix1 ......................pix(r_charw-1) 00000
  199.     
  200. In practice you first cache the font at one bit per pixel (eg use
  201. ZapRedraw_ReadSystemChars) and then convert it to 'n' bits per pixel (for the
  202. current mode) by use of ZapRedraw_ConvertBitmap.
  203.  
  204. Although I have said that the foreground colour must be all 1's and the
  205. background all 0's this is not strictly true. The data poked into the screen
  206. memory is (foreground mask AND bitmap) OR (background mask BIC bitmap). Thus
  207. if you have a foreground mask of &FFFFFFFF and a background mask of 0 then
  208. the bitmap will be poked directly into the screen so can have any format you
  209. like (though character merging and several other features may not work
  210. properly). This idea can be used in conjunction with ZapRedraw_CacheFontChars
  211. to create a fast redraw mode for anti aliased fonts (as used in Zap).
  212.  
  213. Format of text to display (r_data):
  214. -----------------------------------
  215.  
  216. This block contains the text to be printed on the screen. There should be
  217. sufficient text here to redraw the specified area of the screen (given its
  218. size, the scroll offset, character sizes etc). Terminating each line with
  219. the bytes 0,2 will ensure the redraw doesn't run out of text horizontally and
  220. terminating the line list with a zero will ensure the same vertically. The
  221. value in r_data points to a list of words. The n'th word in the list is the
  222. offset (from the block data start) of the n'th line of text to be printed in
  223. the window. This list can be terminated by a 0 offset in which case all
  224. further lines will be cleared to background colour (r_bac).
  225.  
  226. The data for each line consists of a string of bytes giving the characters to
  227. print. By character number 'n' will I mean the n'th (n starting from 0)
  228. bitmap in your character cache in DSA mode or the character with ASCII code
  229. 'n' in VDU redraw mode. The Redraw module does not limit n to the range 0-255
  230. but also allows higher values. Currently you can access 0-65535. Of course,
  231. ASCII characters for the codes 0-31 and 256-65535 are not defined. Zap treats
  232. these specially - see below.
  233.  
  234. The byte 0 in the data for a line introduces a control code. Bytes 1-255 just
  235. print characters n=1-255 as normal so you will need to use control codes to
  236. access characters > 256. The currently defined control sequences are:
  237.  
  238.  0,0        Prints character n=0.
  239.  0,1,f,b    Switch colour to foreground f and background b. (f/b are
  240.         palette offsets - see r_for/r_bac).
  241.  0,2        End of line - the rest of the line is cleared to the current
  242.         background colour.
  243.  0,3,l,h    Print character n=l+h*256.
  244.  0,4,f,b,x,y    Merges the characters x,y. If a pixel is clear in the bitmap
  245.         for y then the pixel is drawn according to the bitmap for x
  246.         and the current for/background colours. If the pixel is
  247.         set for y then the colours f/b are used instead for the x
  248.         pixel. Useful for laying a cursor on top of the character.
  249.         This effect is simulated in VDU mode by using sprites and
  250.         masks. This leaves the current foreground and background
  251.         colours unaltered. NB x and y may contain control codes as
  252.         well. Eg you could have x=0,0 and y=0,3,0,1. If you nest,
  253.         0,4 codes (ie either x or y contain 0,4) then only the most
  254.         deeply nested one will have effect.
  255.  0,5        For internal use only. Restores the stacked values after a
  256.         0,4 call. Putting this in your input string will probably
  257.         cause a crash.
  258.  0,6,f        Change foreground colour to f.
  259.  0,7,b        Change background colour to b.
  260.  0,8,f,b,x,y    Cursor merge of characters x,y. This is similar to 0,4 but
  261.         only works for characters &7F,&100-&105. For &7F, it masks
  262.         in the block simply by changing the for/bac cols of the
  263.         current character being printed. For &100+, the square or
  264.         line is plotted over the top of the character in the
  265.         background colour b.
  266.  0,9,F        Font change to font type F.
  267.  0,10,f,b,F    Switch colour to foreground f and background b, and font
  268.         to font type F.
  269.  
  270. Note that sequences with codes 0,3,4 evaluate to one 'screen printable
  271. character', code 1 to none, and code 2 to as many as is required. Thus it is
  272. not a simple matter to calculate the start of the n'th actual printable
  273. character given a string containing control codes as above. The SWI
  274. ZapRedraw_FindCharacter does this for you.
  275.  
  276. In DSA mode character 'n' just looks up the cached character at address
  277. r_caddr+n*r_cbpc. Usually the bitmaps will correspond to the VDU list
  278. below so that character &20 will be the bitmap for a space etc.
  279.  
  280. In VDU mode character 'n' is interpreted as below:
  281.  
  282.   &00        Prints a '0' (ASCII &30)
  283.   &01-&1A    These print the letters A-Z (ie &40 is added)
  284.   &1B-&1F    Prints "[ \ ] ^ _" respectively (ie &40 is added)
  285.   &20-&7E    Usual ASCII characters printed.
  286.   &7F        This draws a filled in block (useful for a cursor)
  287.   &80-&FF    Usual ASCII characters printed.
  288.   &100        This draws the top,bottom,left edges ie '['.
  289.   &101        This draws the top,bottom edges.
  290.   &102        This draws the top,bottom,right edges ie ']'.
  291.   &103        This draws an empty square (useful for a cursor)
  292.   &104        This draws the baseline ie '_' (useful for a cursor)
  293.   &105        This draws the left edge giving a vertical bar.
  294.   &106+        Undefined action (prints an @ for debugging purposes)
  295.         (More codes may be added in future).
  296.   
  297. The characters are drawn using OS_WriteN/OS_WriteC/OS_Plot (or Font_Paint if
  298. not using the system font).
  299.  
  300. Use ZapRedraw_FindCharacter to jump over the control codes. Use
  301. ZapRedraw_PrepareDataLine to automatically generate the r_data lines from
  302. normal text with foreground and background colour masks. Use
  303. ZapRedraw_AddVduBitmaps to create the bitmaps for character codes 0-&1F,&7F
  304. and >=&100.
  305.  
  306. When using font sub-styles, please note that VDU redraw mode currently only
  307. supports sixteen sub-styles.  It expects bits 0, 5, 6 & 7 to be used for
  308. strikethrough, bold, italic and underlined fonts respectively.
  309. DSA mode doesn't use this convention: you need to change font in an
  310. extension routine there.  DSA redraw allows up to 256 sub-styles to be used.
  311.  
  312. Rendering of bold, italic and bold italic sub-styles has some technical
  313. difficulties associated with the fact that these fonts tend to have different
  314. sized bounding boxes from the default font at the same point size and aspect
  315. ratio.  No attempt is currently made to compensate for this.
  316.  
  317. Format of palette data (r_palette):
  318. -----------------------------------
  319.  
  320. All colours are specified as offsets in the palette table. Thus if you set
  321. r_for to 1 then the module will look up the word at offset 4*1 in the palette
  322. table when it comes to printing a character.
  323.  
  324. DSA MODE: The palette consists of a list of words giving the colour 'mask' to
  325. use for this colour. The mask is duplicated to fill the word out. For
  326. example, in a 16 colour mode, the mask &AAAAAAAA would stand for actual
  327. screen colour 10. The table:
  328.  
  329.         &33333333
  330.         &66666666
  331.         &AAAAAAAA
  332.         &00000000
  333.  
  334. would cause 3 to be poked into the screen when in zap colour 0, 6 when in
  335. zap colour 1 etc. The masks will usually correspond to the wimp colours. The
  336. SWI ZapRedraw_CreatePalette is provided to set them up.
  337.  
  338. The actual value poked into the screen is: (Foreground mask AND bitmap) OR
  339. (Background mask BIC bitmap) where the bitmap is as specified in r_caddr.
  340.  
  341. VDU MODE: The palette consists of a list of words giving the 24 bit colour
  342. required. The word is in the form of a standard palette entry. Ie, &BBGGRRxx
  343. where &BB is the amount of blue etc. These will usually be set up by reading
  344. the wimp palette. The SWI ZapRedraw_CreatePalette will do this for you.
  345. ColourTrans calls will be used during the redraw to find the closest
  346. available GCOL colour.
  347.  
  348. *****************************************************************
  349. * SWI Definitions                        *
  350. *****************************************************************
  351.  
  352. None of the SWI's are re-entrant unless explicitly mentioned. All the SWI's
  353. corrupt R0 and flags and can produce errors.
  354.  
  355. ZapRedraw_RedrawArea (+&00)
  356. ---------------------------
  357.  
  358. This redraws a rectangle of characters on the screen.
  359.  
  360. Entry:    R1=redraw block (as described above).
  361.     All defined offsets in the redraw block are used.
  362.     
  363.     In VDU mode r_workarea must be at least 64 bytes+the amount needed
  364.      for a sprite of one character - see ZapRedraw_SpriteSize.
  365.      If using fonts then the first word of the workarea should contain:
  366.          Lower 16 bits:font size to plot at (points)
  367.          Upper 16 bits:font aspect ratio to use (=Y/Xx100) (or 0)
  368.  
  369.     In DSA mode r_workarea must be at least 64+r_cbpl bytes (and a
  370.      whole number of words long).
  371.      If b2 of the r_flags word is set then you provide an extension
  372.      routine and:
  373.       R2=address of the routine
  374.       R3=private word value to pass to the routine.
  375.  
  376. Exit:    R0 and flags corrupted.
  377.  
  378. The extension routine is provided so you can trap unknown control codes and
  379. add extra functionality to the ones that exist. For example, you may wish to
  380. change font on a colour change. Zap's fast font redraw mode does this. If you
  381. provide an extension routine then on entry to it R0=reason code R12=your
  382. private word and:
  383.  
  384.  R0=0 => Starting a raster line:
  385.      R1=redraw block
  386.      R3=address of first character
  387.      R4=r_caddr+r_cbpl*row where row (0 ... r_charh-1) is the current
  388.         character row being drawn. Or, R4=0 if in line spacing.
  389.      R5=screen address of current word being written
  390.      R6=bit offset in current word being written
  391.      R7=current word being writen (bits >= R6 are clear)
  392.      R9=foreground/background colour numbers:
  393.         foreground:bottom sixteen bits, background: top sixteen bits.
  394.      R10=start foreground mask (eg &77777777)
  395.      R11=start background mask (eg &00000000)
  396.  
  397.  R0=1 => Foreground and background colours changing (control code 0,1)
  398.      Registers as above (except R9 not set up) with R3=next character
  399.      after the control code and R10,R11 new foreground/background masks
  400.      etc.
  401.  
  402.  R0=4 => About to merge characters (control code 0,4)
  403.      R1=redraw block
  404.      R2=character defn table to use for the mask character
  405.      R3=next character after the merge
  406.      R4=character defn table for the base character (as for R0=1)
  407.      R6=base char
  408.      R7=mask char (or these are -1 if invalid).
  409.      R8/R9=for/bac masks where mask character bits set.
  410.      R10/R11=current for/bac masks.
  411.      NB Any changes you make to these registers will be effective for
  412.      this one character only the normal values being stacked.
  413.  
  414.  R0=6 => Foreground colour changing (control code 0,6)
  415.      Registers as for R0=1.
  416.  
  417.  R0=7 => Background colour changing (control code 0,7)
  418.      Registers as for R0=1.
  419.  
  420.  R0=8 => About to cursor merge characters (control code 0,8)
  421.      Registers as for R0=4
  422.      If R7<&100 then R10/R11 will be set to R9/R8 and next char drawn
  423.      If R7>=&100 then the characters will be merged with R9
  424.      copied into R8.
  425.  
  426.  R0=9 => Font change
  427.      Registers as for R0=1
  428.  
  429.  R0=10=> Foreground colour, background colour and font change
  430.      Registers as for R0=1
  431.      
  432.      Note that if changing font during redraw, then this must be done
  433.      in an extension routine for DSA redraws.
  434.  
  435.  R0=2,3,5,>10     Reserved - ignore.
  436.  
  437.  Exit:  You may corrupt R0 and R12 and alter the registers mentioned
  438.     (except R1!) to new (sensible) values.
  439.     All registers are reset at the start of a new raster line.
  440.     You must not alter the redraw block itself.
  441.     You CANNOT return errors from an extension call.
  442.  
  443. ZapRedraw_GetPaletteEntry (+&01)
  444. --------------------------------
  445.  
  446. This SWI takes a colour bitmap and duplicates it to fill a word, creating
  447. a mask as needed for r_palette in DSA mode. Eg if R0=7 and R1=2 on entry then
  448. R0=&77777777 on exit.
  449.  
  450. Entry:    R0=The colour number to be poked into the screen. (0->num_of_cols-1)
  451.     R1=r_bpp (0-5)
  452.  
  453. Exit:    R0=Mask to put in palette table (with colour duplicated to fill the
  454.     word).
  455.  
  456. ZapRedraw_RedrawRaster (+&02)
  457. -----------------------------
  458.  
  459. Redraws a single raster line. Only applies to non-vdu redraw. This is a low
  460. level call used by ZapRedraw_RedrawArea and not of much use otherwise.
  461.  
  462. Entry:    R1=redraw block
  463.            Offsets used are: r_flags,r_minx,r_maxx,r_bpp,r_charw,r_charh
  464.             r_cbpl,r_cbpc,r_palette,r_workarea.
  465.     R3=address of text to use for this line starting at the first
  466.        visible character.
  467.     R4=address of character defn table with row offset added so redraw
  468.        uses first 'row' of each bitmap, or set to 0 if you want the
  469.        line to be cleared to the background colour (eg interline gap).
  470.     R5=screen address of the start of the raster line.
  471.     R6=b0-b15    = start foreground colour to use (eg r_for value)
  472.        b16-b24    = start background colour to use (eg r_bac value)
  473.        b24-b31    = starting font
  474.     The initial words of r_workarea are set up as follows:
  475.     #0 Pixel scroll offset within the first visible char (0->charw-1)
  476.     #4 Number of pixels to do from the first character   (0->charw-1)
  477.     #8 Number of whole characters to do after the first char
  478.     #12 Number of pixels to do in the last visible char  (0->charw-1)
  479.     #16 -
  480.     #20 Address of extension sub if redraw flags bit 2 set
  481.     #24 Extension sub private word pointer redraw flags bit 2 set
  482.  
  483. Exit:    R0 and flags corrupted.
  484.  
  485. ZapRedraw_ConvertBitmap (+&03)
  486. ------------------------------
  487.  
  488. This SWI takes a character bitmap of the form of 1 bit per pixel, (the bit
  489. set for foreground/clear for background) and converts it into a bitmap for
  490. use by the RedrawArea SWI, by changing each '1' to n '1's and each '0' to
  491. n '0's where 'n' is the number of bits per pixel given. It uses the SWI
  492. ZapRedraw_ConvBitmapChar to do this.
  493.  
  494. Entry:    R1=redraw block, offsets looked at are:
  495.     r_bpp        To find the number of bits per pixel.
  496.     r_charw        Width of char in pixels
  497.     r_charh        Height of char in pixels
  498.     r_caddr        Address to write the bitmap. Memory at offsets
  499.             R2*r_cbpc to (R3+1)*r_bpc must be preserved
  500.     r_cbpl        Cache line width in bytes (as defined under
  501.             r_caddr help text)
  502.     r_cbpc        Number of bytes per cached character (as defined
  503.             under r_caddr help text)
  504.     R2=First character to be converted (eg 0)
  505.     R3=Last character to be converted (inclusive) (eg 255)
  506.     R4=Address of source bitmap of the format described under r_caddr
  507.        but with 1 bit per pixel (ie 2 colour mode format)
  508.  
  509. Exit:    r_caddr block written to.
  510.     R0 and flags corrupted.
  511.  
  512. ZapRedraw_PrepareDataLine (+&04)
  513. --------------------------------
  514.  
  515. This SWI is to help prepare the 'r_data' field of the redraw block. It takes
  516. as input the pointer to a line of text character (0-255) to be treated as
  517. ordinary characters (0 is not a control code). It also takes as input a
  518. pointer to a background mask and a foreground mask list, giving the
  519. background and foreground colours of each character separately. The output is
  520. a line of the format required by 'r_data' with control codes changing the
  521. colours and specifying the line end. Control codes in the input string can
  522. have their colour set automatically by setting R0 to the colour.
  523.  
  524. Eg: Input:
  525.  
  526.     Text input (characters): "HELLO WORLD         "
  527.     Foreground (bytes list):  11111122222222222222
  528.     Background (bytes list):  00000000000000000000
  529.     Start background 0
  530.     Start foreground 1
  531.     Input length 20
  532.  
  533.     Output: "HELLO ",0,1,2,0,"WORLD",0,2 (highest letter used = "W").
  534.  
  535. Entry:    R0=foreground colour to use for control characters (0-&1F) or
  536.        set to -1 if you do not wish ctrl chars to be specially treated.
  537.     R1=redraw block giving start foreground background colours in
  538.        r_for,r_bac - nothing else used.
  539.     R2=pointer to text input string (length in R5)
  540.     R3=pointer to foreground mask (length in R5)
  541.     R4=pointer to background mask (length in R5)
  542.     R5=length of inputs in bytes
  543.     R6=destination buffer (length must be at least 6*R5+16 to ensure
  544.        it is big enough - colour change + 0 -> 0,0 + terminator).
  545.         R7=font mask... (not supplied if b3 of r_flags is zero)
  546.  
  547. Exit:    R0=highest used character code used (ie &20-&FF). You may not
  548.     want to cache all font characters as usually those >= 128 are not
  549.     needed. This tells you the range you MUST cache.
  550.     R5=length of output string (including 0,2 terminator)
  551.     Only a subset of the the redraw codes available are used.
  552. Note:   Bit 3 of any font data supplied is used to control the
  553.     'Inverse video' effect.  While this bit is set, foreground and
  554.     background colours are swapped over in all operations.
  555.  
  556. ZapRedraw_AddCursor (+&05)
  557. --------------------------
  558.  
  559. This SWI takes a line of the same format used in 'r_data', eg the output from
  560. the above SWI, and adds in the codes to place 'cursors' over some of the text
  561. by using the code 0,4 (merge characters) or the code 0,8 (merge cursors).
  562. Here, a cursor means a string of characters to be overlayed.
  563.  
  564.  Entry:    R0=destination string
  565.     R1=redraw block giving initial r_for and r_bac.
  566.     R2=offset in source string of first character to be in the cursor
  567.     R3=cursor length (length in characters of string pointed to by R4)
  568.     R4=pointer to string of cursor characters (usually &7Fs)
  569.     R5=source string (0,2 terminated)
  570.     R6=swap colour/-1 if none. If the character having the cursor placed
  571.        over it has this foreground colour then the cursor bac/foreground
  572.        cols are swapped over (eg in a selected region).
  573.     R7=b0-b7   high byte to use for cursor characters in R4 string
  574.        b8-b15  control code to use when merging ie 4 or 8.
  575.        b16-b23 foreground colour of the cursor
  576.        b24-b31 background colour of the cursor
  577.     Room should be reserved for the string to grow by 8*R3
  578.     characters. (eg 0,4,f,b,old,0,3,l,h) If the indicated offset (R2)
  579.     is off the end of the string then it will be lengthened with spaces
  580.     (&20) so you should ensure R2+9*R3 characters extra are reserved.
  581.     
  582.  Exit:    R0=end of new destination string (after 0,2 terminator)
  583.  
  584. ZapRedraw_FindCharacter (+&06)
  585. ------------------------------
  586.  
  587. This SWI takes as input a line of the format required by 'r_data' (ie
  588. containing ctrl sequences starting with 0) and a number 'n' and returns the
  589. start of the (n+1)'th printable character within this line (ie it skips over
  590. n printable characters), ignoring colour change control codes etc. Thus on
  591. exit it points to a byte 1-255 or one of the control sequences 0,0 or 0,2 or
  592. 0,3,l,h or 0,4,f,b,c1,c2 each of which define one printable character. If the
  593. offset n is off the end of the line then it will point to the 0,2 terminator.
  594. It also keeps track of the colour changes that take place. NB If n=0 then it
  595. may still be useful - as it will jump over any colour changes before the
  596. first character. If R0>R1 on exit then the character was found, otherwise
  597. there were R1-R0 characters left to skip.
  598.  
  599. Eg: Input:    "hello ",0,1,2,3,"goodbye",0,2
  600.     Output:    If n=0 then it will point to the 'h'
  601.         If n=6 then it will point to the 'g'
  602.         If n=100 then it will point to the 0 of 0,2.
  603.  
  604.  Entry:        R0=n (number of characters to skip)
  605.              (or -1 to move to the end of the string - find its len)
  606.         R1=pointer to the input string (terminated by 0,2)
  607.         R2=current foreground colour
  608.         R3=current background colour
  609.         
  610.  Exit:        R0=If the n'th character is in the string then this points
  611.             to the end of the n'th character (start in R1)
  612.            If the n'th 'character' is the terminator (0,2) then this
  613.             equals R1 (start of the terminator)
  614.            If it reached the string terminator before the n'th
  615.             character then this is R1-number of chars not skipped
  616.         R1=start of the next printable character after skipping n.
  617.            (or string terminator if reached that first).
  618.         R2-R3 updated by any colour change control codes.
  619.         Flags corrupted.
  620.  
  621. ZapRedraw_MoveBytes (+&07)
  622. --------------------------
  623.  
  624. This is a fast byte shifting SWI. Highly optimised and bytes are shifted
  625. starting at the top or bottom depending on whether the destination address is
  626. higher or lower than the start (respectively). Thus the data is always
  627. preserved.
  628.  
  629.  Entry:        R1=source address (need not be word aligned)
  630.         R2=destination address (need not be word aligned)
  631.         R3=number of bytes to move (>=0)
  632.  
  633.  Exit:        R0-R3 and flags corrupted.
  634.  
  635. ZapRedraw_CachedCharSize (+&08)
  636. -------------------------------
  637.  
  638. This SWI works out the values of r_cbpl,r_cbpc from r_charw,r_charh,r_bpp in
  639. the manner defined under the help text on r_caddr. Ie, r_cbpl is either 1,2,
  640. or a multiple of 4 and r_cbpc=r_charh*r_cbpl.
  641.  
  642.  Entry:        R0=r_bpp value
  643.         R2=r_charw value
  644.         R3=r_charh value
  645.         
  646.  Exit:        R2=number of bytes per cache line (r_cbpl)
  647.         R3=number of bytes per cached character (r_cbpc)
  648.  
  649. ZapRedraw_ConvBitmapChar (+&09)
  650. -------------------------------
  651.  
  652. This SWI is for the use of the ConvertBitmap SWI and performs the bitmap
  653. conversion for one character. It takes a bit map of the one bit per pixel
  654. format and expands it to have n=2^R7 bits per pixel by replacing each '0'
  655. with n '0's and each '1' with the mask in R6 (usually n '1's). Thus for
  656. standard conversion you should set R6 to be 2^n-1 (=2^(2^R7)-1). (NB if R7
  657. (=r_bpp) is zero then all you have to do is copy the bitmap. R7=0 is not
  658. supported by this call.
  659.  
  660.  Entry:        R1=redraw block (only r_charh is used to find the height of
  661.            the character in pixels).
  662.         R2=bytes per cache line for the source character (1,2,*4)
  663.         R3=bytes per cache line for the dest character (1,2,*4)
  664.         R4=pointer to source character bitmap
  665.         R5=address to place destination character bitmap
  666.         R6=bit mask to insert in place of 1's (only bottom 2^R7 bits)
  667.         R7=Log_2 of number of bits per pixel (1-5)
  668.  
  669.  Exit:        R4 and R5 updated to the start of the 'next' characters.
  670.         R0 and flags corrupted.
  671.  
  672. ZapRedraw_CreatePalette (+&0A)
  673. ------------------------------
  674.  
  675. This SWI is used to create the r_palette data block. If R0=1 on entry then it
  676. takes a palette consisting of a list of wimp colour numbers (one per word)
  677. and converts it to entries of the form &BBGGRRxx, a 24 bit palette entry by
  678. using the call Wimp_ReadPalette and duplicating the nibbles. If R0=2 on entry
  679. then it takes a list of entries of the form &BBGGRRxx and converts them to
  680. colour masks required for DSA redraw (see r_palette) using ColourTrans calls
  681. and ZapRedraw_GetPaletteEntry. If R0=3 on entry then it does both, converting
  682. wimp colour numbers to DSA redraw masks.
  683.  
  684.  Entry:        R0=reason code:
  685.              b0 Set to convert wimp cols to &BBGGRRxx
  686.              b1 Set to convert &bbggrrxx to DSA colour masks
  687.              b2+ reserved - set to 0
  688.         R1=redraw block. The following are used:
  689.            r_bpp      = log_2 of bits per pixel
  690.            r_workarea = pointer to 128 byte work area to load wimp
  691.                    palette into.
  692.         R2=address of source palette
  693.         R3=address for dest palette (needs 4*R4 bytes preserved)
  694.            (source may equal destination)
  695.         R4=number of palette entries (eg 16)
  696.  
  697.  Exit:        R0 and flags corrupted.
  698.  
  699. ZapRedraw_InsertChar (+&0B)
  700. ---------------------------
  701.  
  702. This inserts a single character into a string of r_data format. If R0=0 then
  703. it inserts 0,0 and if R0>=&100 then it inserts 0,3,x,y where R0=&yyxx.
  704. Otherwise it just inserts the byte as normal.
  705.  
  706.  Entry:        R0=character
  707.         R1=string address
  708.         
  709.  Exit:        R1 updated 'till after the character
  710.         R0 and flags corrupted.
  711.  
  712. ZapRedraw_ReadSystemChars (+&0C)
  713. --------------------------------
  714.  
  715. This reads the standard system characters bitmaps via OS_Word calls. It reads
  716. them in 1 bit per pixel (8 bytes per character) form suitable for
  717. ZapRedraw_ConvertBitmap to convert it to a form usable for
  718. ZapRedraw_RedrawArea. To do this, it just bit-reverses the information read
  719. by OS_Word,10. It only reads characters &20-&FF, leaving 0-&1F untouched. The
  720. bit reversing is done efficiently so this call is fairly fast.
  721.  
  722.  Entry:        R0=buffer for bitmap (size 8*256=&800=2k)
  723.         R1=redraw block. r_workarea must be a 16 byte work area.
  724.         
  725.  Exit:        R0 and flags corrupted.
  726.  
  727. ZapRedraw_ReverseBitmaps (+&0D)
  728. -------------------------------
  729.  
  730. This SWI takes a list of bytes and reverses the bits of each byte. This is
  731. useful for reversing the bitmaps (flipping about the y axis) of 8*8 pixel
  732. characters at one bit per pixel (ie r_cbpl=1 r_cbpc=8).
  733.  
  734.  Entry:        R1=source buffer
  735.         R2=destination buffer (can equal source)
  736.         R3=number of bytes (must be a multiple of 4)
  737.  
  738.  Exit:        R0 and flags corrupted.
  739.  
  740. ZapRedraw_ReadVduVars (+&0E)
  741. ----------------------------
  742.  
  743. This SWI is used to set up the Zap redraw block initially. It puts the value
  744. 0 in r_screen so the actual screen address is used when ZapRedraw_RedrawArea
  745. is called (this can change quite often) and fills in r_bpl, r_bpp, r_magx,
  746. r_magy, r_xsize, r_ysize by using the call OS_ReadVduVariables. It also fills
  747. in r_mode by using OS_Byte 135. This call should be made after any mode
  748. change. Compensation is made for double pixel modes by decreasing r_magx. A
  749. pixel in Zap means a hardware pixel rather than an emulated double pixel.
  750.  
  751.  Entry:        R1=redraw block to update
  752.            r_workarea should point to a 64 byte scratch area.
  753.  
  754.  Exit:        R0 and flags corrupted.
  755.  
  756. ZapRedraw_GetRectangle (+&0F)
  757. -----------------------------
  758.  
  759. This SWI should be used after calls to Wimp_GetRectangle. It takes the redraw
  760. rectangle block as returned by Wimp_RedrawWindow or Wimp_GetRectangle and
  761. uses it to fill in the ZapRedraw block. The scroll offsets of the update
  762. rectangle are in pixels. The y scroll offset is the amount 'down' from the
  763. work area origin (inclusive), so negating will get the 'upward' scroll
  764. offset in pixels (exclusive), and the shifting by r_magy will give the
  765. normal OS work area scroll offset (which is exclusive).
  766.  
  767.  Entry:        R0=block as returned by Wimp_RedrawWindow/Wimp_GetRectangle
  768.            ie: window handle,minx,miny,maxx,maxy,scrollx,scrolly etc
  769.         R1=Zap redraw block with r_magx,r_magy,r_xsize,r_ysize
  770.            filled in.
  771.  
  772.  Exit:        r_minx,r_miny,r_maxx,r_maxy,r_scrollx,r_scrolly have been
  773.         filled in in the redraw block pointed to by R1.
  774.         R0 and flags corrupted.
  775.  
  776. ZapRedraw_AddVduBitmaps (+&10)
  777. ------------------------------
  778.  
  779. If you look at the VDU codes, you will see that characters 0-&1F,&7F,&100+
  780. are treated specially during a VDU redraw, drawing blocks and squares. The
  781. purpose of this SWI is to create bitmaps for these extra characters from a
  782. standard bitmap of the normal characters, so you can also use these in a DSA
  783. redraw. You specify an interval of characters, and in that interval, it
  784. creates bitmaps for the following:
  785.  
  786.     &00    Creates bitmap for '0' by copying bitmap &30
  787.     &01-&1F Creates bitmap for 'AB...' by copying bitmaps &41-&5F
  788.     &7F    Creates a filled in square.
  789.     &100    Top bottom and left edge filled [
  790.     &101    Top and bottom edges
  791.     &102    Top bottom and right edge filled ]
  792.     &103    Empty square
  793.     &104    Underscore _
  794.     &105    Left edge (giving a bar)
  795.     &106+    Undefined (currently copies the @ character).
  796.     
  797. This means that the bitmaps will then be consistent with the VDU characters
  798. of these numbers. These bitmaps are also useful as cursors.
  799.  
  800.  Entry: R1=redraw block (uses r_charw and r_charh to find the char size)
  801.        r_workarea must have 64 bytes + room for a character sprite
  802.        (see ZapRedraw_SpriteSize) reserved.
  803.         R2=first extra bitmap to create (eg 0)
  804.         R3=last extra bitmap to create (inclusive eg &104)
  805.         R4=address of bitmaps in 1 bit per pixel form.
  806.            (space must be reserved for the characters to be created).
  807.  
  808.  Exit:    R0 and flags corrupted.
  809.  
  810. ZapRedraw_CacheFontChars (+&11)
  811. -------------------------------
  812.  
  813. This SWI takes an anti-aliased font and caches a range of characters as
  814. bitmaps (see r_caddr). The cacheing can be done in any colours or screen
  815. resolution. Of course only those with foreground colour all bits set and
  816. background colour all bits clear can be used directly by
  817. ZapRedraw_RedrawArea. However, by giving a foreground colour mask of -1 and a
  818. background mask of 0 any bitmap can be drawn (see r_caddr etc). An hourglass
  819. is given with the % as the current character/256 if it takes a long time.
  820.  
  821.  Entry:    R0=reason code and other registers as below.
  822.           
  823.   R0=1 => Cache font in current wimp mode (ie wimp palette used).
  824.       R1=redraw block with the following set up:
  825.         r_bpp = number of bits per pixel to cache at
  826.         r_caddr = address of cache with space reserved for the chars
  827.         r_cbpl/cbpc/r_charw/r_charh setup
  828.         r_for/r_bac = offset in r_palette of for and bac cols
  829.         r_palette = palette of colours as for VDU redraw mode
  830.                 (ie each entry of form &BBGGRRxx)
  831.         r_workarea = room for 64 bytes + single sprite
  832.                  (use ZapRedraw_SpriteSize).
  833.         r_mode = mode to cache font in (ie mode sprite defined in).
  834.       R2=pointer to font name
  835.       R3=Lower 16 bits:font size to plot at (points)
  836.          Upper 16 bits:font aspect ratio to use (=Y/Xx100) (or 0)
  837.       R4=x os offset (from bottom left) to plot character in the box
  838.       R5=y os offset (from bottom left) to plot character in the box
  839.       R6=first character to cache (0 caches as &30 and 1-&1F have &40
  840.          added &7F is ignored).
  841.       R7=last character to cache (inclusive)
  842.  
  843.   R0=2 => Cache font in mode 0 with background 0 and foreground 1.
  844.       R1=redraw block with the following set up:
  845.         r_caddr = address of cache with space reserved for the chars
  846.         r_cbpl/cbpc/r_charw/r_charh setup
  847.         r_workarea = as for R0=1
  848.         r_magx,r_magy for mode used with reason code R0=1
  849.       R2-R7 as for reason code R0=1.
  850.       Font size is scaled up by 2^(1-r_magx) horizontally and
  851.       2^(2-r_magy) vertically so the characters are the same pixel
  852.       size as those cached with R0=1.
  853.       
  854.  Exit: R0 and flags corrupted.
  855.  
  856. ZapRedraw_SpriteSize (+&12)
  857. ---------------------------
  858.  
  859. Several SWI's (eg ZapRedraw_RedrawArea - VDU mode, ZapRedraw_CacheFontChars)
  860. need to create a sprite area the size of a single character. This call
  861. returns the size required for this sprite (+palette+mask+save area etc), and
  862. thus the amount of workarea that should be reserved. The sprite needs a save
  863. area as it appears that Font_Paint redirects output to a sprite and thus
  864. corrupts the graphics colours. This means that it takes two passes to read
  865. the size required for the sprite - the first to read the size for the sprite
  866. and the second to create the sprite (space now reserved for it) and calculate
  867. the save area required via OS_SpriteOp,62.
  868.  
  869.  Example: SYS "ZapRedraw_SpriteSize",&01,redraw_block TO size%
  870.       PROCensure_workarea(size%)
  871.       SYS "ZapRedraw_SpriteSize",&81,redraw_block TO size%
  872.       PROCensure_workarea(size%)
  873.  (NB In practice the SWI usually requires 64+size% bytes of workspace)
  874.  
  875.  Entry:    R0=reason code
  876.        b0-b6 1=return sprite size for sprite in current mode and r_bpp
  877.              2=return sprite size for a mode 0 sprite (ie assume r_bpp=0)
  878.        b7    Clear for first pass, set for second pass.
  879.     R1=redraw block with r_bpp,r_charw,r_charh setup.
  880.        On the second pass r_workarea must be at least the size returned
  881.        by the first pass.
  882.     
  883.  Exit:  On first pass : R0=size required for sprite area (no save area).
  884.     On second pass: R0=total size required for sprite + save area.
  885.  
  886. ZapRedraw_RedrawWindow (+&13)
  887. -----------------------------
  888.  
  889. This SWI performs the calls to Wimp_RedrawWindow, Wimp_GetRectangle,
  890. Zap_GetRectangle, and Zap_RedrawArea for you. It assumes that the redraw
  891. block is already setup. This call is equivalent to the basic code:
  892.     SYS "Wimp_RedrawWindow",,data% TO flag%
  893.         WHILE flag%
  894.          SYS "ZapRedraw_GetRectangle",data%,redraw%
  895.          SYS "ZapRedraw_RedrawArea",,redraw%
  896.          SYS "Wimp_GetRectangle",,data% TO flag%
  897.         ENDWHILE
  898. where redraw% is the address of the redraw block and data% the data block
  899. returned by Wimp_Poll for event 1 (redraw window request).
  900.  
  901.  Entry:    R0=Redraw block as returned by Wimp for Wimp_Poll 1 (data%)
  902.     R1=Zap redraw block with r_data containing the text to redraw. All
  903.        of the block should be setup apart from rectangle to draw
  904.        and the scroll offsets which are filled in for you.
  905.        
  906.  Exit:    R0 and flags corrupted.
  907.  
  908. ZapRedraw_Divide (+&14)
  909. -----------------------
  910.  
  911. This SWI performs fast division and modulo functions.  As the SWI overhead
  912. may be significant for this routine you may wish to find its address and
  913. call it directly.
  914.  
  915.  Entry:    R0=numerator
  916.     R1=denominator
  917.  
  918.  Exit:    R0=R0 DIV R1 
  919.      R1 corrupted.
  920.      R2=R0 MOD R1
  921.      R3 corrupted if the denominator is greater than 32.
  922.  
  923. ZapRedraw_PlotRectangle (+&15)
  924. ------------------------------
  925.  
  926. This SWI performs fast plotting of rectangles.  It is used internally as a
  927. drop in replacement for the operating system's routines.
  928.  
  929. The routine doesn't clip to the graphics window.  It would be inefficient
  930. for it to do so - typically the graphics window co-ordinates normally only
  931. need to be read once for a number of rectangles.
  932.  
  933.  Entry:    R0 = left   X (inclusive)
  934.         R1 = top    Y (inclusive)
  935.         R2 = right  X (exclusive)
  936.         R3 = bottom Y (exclusive)
  937.         R4 = colour (filled word - see ColourTrans_ReturnColourNumber)
  938.  
  939. Coordinates are in pixels, (0,0) at top left
  940.  
  941. It is required that R2>R0, and R3>R1.
  942.  
  943. All co-ordinates must be positive and within display bounds.
  944.  
  945.  Exit:    R0-R12 corrupted.
  946.